home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 6 / CU Amiga Magazine's Super CD-ROM 06 (1996)(EMAP Images)(GB)(Track 1 of 4)[!][issue 1997-01].iso / imagine / extras / tools / isl3_0b6 / docs / isl.doc < prev    next >
Text File  |  1994-11-01  |  6KB  |  132 lines
  1. ISL.doc - Copyright (c) 1994 Grizzly Bear Labs, last modified 11-01-94
  2.  
  3. ISL, the Imagine Staging Language, is a language created to make the
  4. generation and manipulation of Imagine 3.0 staging files a whole lot
  5. easier.  If you have ever used the Action editor in earnest, you know
  6. that certain types of operations are easy (such as adding a single
  7. light) while others are not (such as adding more frames and causing
  8. your existing objects to appear in them).
  9.  
  10. ISL provides an alternative interface to the Action editor.  With ISL,
  11. you can create your stage using the Stage and Action editors as needed,
  12. then convert it to a fairly straightforward ASCII format, edit it as
  13. desired using your favorite text editor, then put it back!  This is of
  14. course the simplest way of using ISL - you could also create stages
  15. programatically.  I have done this myself.
  16.  
  17. To use ISL productively, it is first necessary to understand a bit about
  18. how Imagine works.  Quite a bit.  I would not attempt to use this package
  19. if you are not comfortable with Imagine.  If you are struggling, I would
  20. recommend that you purchase Steve Worley's excellent book on the topic,
  21. "Understanding Imagine 2.0", read it, then come back (plug).  Even though
  22. it doesn't support Imagine 3.0 directly, it is still highly relevant.
  23.  
  24. Back?  Good.  When you first create a Project in Imagine 3.0, Imagine
  25. creates a staging file in your whatever.imp directory.  This staging
  26. file, run through the ISL de-compiler destage, looks like this:
  27.  
  28.     STAGE
  29.     MAXFRAMES 1
  30.     LOOP 0
  31.  
  32. The command to generate this file or one like it is:
  33.  
  34.     destage binarystage asciistage
  35.  
  36. where binarystage is the Imagine staging file and asciistage is where you
  37. want to put the ISL.
  38.  
  39. The ISL compiler will indeed eat this simple stage format.  Let's say you
  40. just want to add some frames.  You would then have something like this:
  41.  
  42.     STAGE
  43.     MAXFRAMES 100
  44.     LOOP 0
  45.  
  46. The command to make this into a valid Imagine stage is:
  47.  
  48.     restage asciistage binarystage
  49.  
  50. where asciistage is your modified ISL source file and binarystage is where
  51. you want to put the new Imagine stage.  A word of caution:  it never hurts
  52. to make a backup copy of a staging file before stomping it!
  53.  
  54. That was too easy.  Onto ISL complexity level two.  :-)  If you bring up the
  55. Action editor and save the stage, without touching it, it will magically
  56. grow into something like this:
  57.  
  58.     STAGE
  59.     MAXFRAMES 1
  60.     LOOP 0
  61.  
  62.     CAMERA "CAMERA" LAYER 0
  63.     POSITION FRAMES 1 1 XYZ 160. -320. 160. VELOCITY 1. 1. SPLINE
  64.     ALIGN FRAMES 1 1 XYZ 0. 0. 0. VELOCITY 1. 1.
  65.     SIZE FRAMES 1 1 XYZ 320. 640. 233.333328 VELOCITY 1. 1.
  66.  
  67.     GLOBALS "GLOBALS" LAYER 0
  68.     ACTOR FRAMES 1 1 BRUSH "" 0 BACKDROP "" 0 AMBIENT RGB 0. 0.
  69.     0. HORIZON RGB 0. 0. 0. +ZENITH RGB 0.
  70.     0. 0. -ZENITH RGB 0. 0. 0. FOG BTL
  71.     0. 0. 0. FOG RGB 0. 0. 0.
  72.     STARFIELD 0. TRANSITION 0
  73.  
  74. Note the addition of a CAMERA clause and a GLOBALS clause.  Some detail is
  75. called for at this point.  ISL sentences generally correspond one-for-one
  76. to Action editor entries.  There will be one line containing the name and
  77. layer from the far left-hand column of the Action editor entry (CAMERA
  78. "CAMERA" LAYER 0 or GLOBALS "GLOBALS" LAYER 0, etc.) followed by one line
  79. for each line or line segment in the Action editor.
  80.  
  81. So, for this simple stage, we have three clumps - the stagehdr, containing
  82. the STAGE, MAXFRAMES and LOOP clauses, the CAMERA clump, containing the name
  83. clause, a position clause, an alignment clause, and a size clause, and the
  84. globals clump, containg the name and the actor info.
  85.  
  86. Here is an ISL object entry, showing what happens when you swap three
  87. physical objects while changing their position and alignment:
  88.  
  89. OBJECT "PORTAL" LAYER 0
  90. ACTOR FRAMES 1 40 NAME "Portal.imp/objects/Portal" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
  91. ACTOR FRAMES 41 60 NAME "Portal.imp/objects/Prtal" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
  92. ACTOR FRAMES 61 100 NAME "Portal.imp/objects/Prtl" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
  93. POSITION FRAMES 1 40 PATH "PATH" ACCEL 0 0. DECEL 0 0.
  94. POSITION FRAMES 41 100 XYZ 0. -1000. 0. VELOCITY 1. 1. SPLINE
  95. ALIGN FRAMES 1 1 XYZ 0. 0. 0. VELOCITY 1. 1.
  96. ALIGN FRAMES 2 20 XYZ 0. 180. 0. VELOCITY 1. 1.
  97. ALIGN FRAMES 21 39 XYZ 0. 360. 0. VELOCITY 1. 1.
  98. SIZE FRAMES 1 1 XYZ 32. 32. 32. VELOCITY 1. 1.
  99.  
  100. Again, we start with the object name and layer, then follow it with one ISL line
  101. for each Action editor line or line segment.  Note that there are two types of
  102. POSITION line here - the first follows a path "PATH", and the second is
  103. a tween position.  This example is from my flying Portal logo anim.
  104.  
  105. Here is another ISL object entry, showing an object with a SPFX clause:
  106.  
  107. OBJECT "EMERALD" LAYER 0
  108. ACTOR FRAMES 1 12 NAME "Emerald.imp/objects/emerald2.obj" STATE "" CYCLE 0. 0. VELOCITY 1. 1.
  109. POSITION FRAMES 1 1 XYZ 0. 0. 0. VELOCITY 1. 1. SPLINE
  110. ALIGN FRAMES 1 1 XYZ 0. 0. 3.750000 VELOCITY 1. 1.
  111. SIZE FRAMES 1 1 XYZ 5. 5. 6.500000 VELOCITY 1. 1.
  112. EFFECT 1 FRAMES 1 12 Rotate20 "Effects/Rotate20" ZAXIS DEGREES 45.
  113.  
  114. Each Special Effect has it's own syntax.  Use EFFECT 1 for SF/X 1, EFFECT 2
  115. for SF/X 2.  The individual syntax for each effect is documented in ISL.BNF.
  116. Note that an effect is actually recognized by the fifth word, which in this
  117. case is Rotate20 - this following clause is the filename in quotes, so that
  118. your effects can live anywhere.
  119.  
  120. I think this ought to be enough to get started using ISL.  The actual syntax
  121. of the language is documented in the included ISL.BNF file.  The easiest way
  122. to get started would probably be to try destage-ing, modifying, and restage-
  123. ing your own files.  I'd stay out of ISL.BNF until you are pretty familiar
  124. with ISL or are stuck.
  125.  
  126. Hey, wait a minute, what about frames.c?  Oh, yeah.  It's a little stage
  127. generator I whipped up.  It's written in c, and produces a bunch of frames
  128. ready to be averaged together (for motion blur, of course).  Take it not as
  129. an example of sheer programming elegance, but rather as an idea of how to
  130. programmatically generate an ISL stage.
  131.  
  132.